'\" te
.\"  Copyright 1989 AT&T  Copyright (c) 1997, Sun Microsystems, Inc.  All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
.\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with
.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH MONITOR 3C "Dec 29, 1996"
.SH NAME
monitor \- prepare process execution profile
.SH SYNOPSIS
.LP
.nf
#include <mon.h>

\fBvoid\fR \fBmonitor\fR(\fBint (*\fR\fIlowpc\fR(), \fBint (*\fR\fIhighpc\fR)(), \fBWORD *\fR\fIbuffer\fR, \fBsize_t\fR \fIbufsize\fR,
     \fBsize_t\fR \fInfunc\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBmonitor()\fR function is an interface to the \fBprofil\fR(2) function
and is called automatically with default parameters by any program created by
the \fBcc\fR utility with the \fB-p\fR option specified. Except to establish
further control over profiling activity, it is not necessary to explicitly call
\fBmonitor()\fR.
.sp
.LP
When used, \fBmonitor()\fR is called at least at the beginning and the end of a
program. The first call to \fBmonitor()\fR initiates the recording of two
different kinds of execution-profile information: execution-time distribution
and function call count. Execution-time distribution data is generated by
\fBprofil()\fR and the function call counts are generated by code supplied to
the object file (or files) by  \fBcc\fR \fB-p.\fR Both types of information are
collected as a program executes. The last call to \fBmonitor()\fR writes this
collected data to the output file \fBmon.out\fR.
.sp
.LP
The name of the file written by \fBmonitor()\fR is controlled by the
environment variable \fBPROFDIR\fR. If \fBPROFDIR\fR does not exist, the file
\fBmon.out\fR is created in the current directory. If \fBPROFDIR\fR exists but
has no value, \fBmonitor()\fR does no profiling and creates no output file. If
\fBPROFDIR\fR is \fBdirname\fR, and \fBmonitor()\fR is called automatically by
compilation with \fBcc \fR\fB-p\fR, the file created is
\fBdirname\fR\fB/\fR\fIpid.progname\fR where \fIprogname\fR is the name of the
program.
.sp
.LP
The \fIlowpc\fR and \fIhighpc\fR arguments are the beginning and ending
addresses of the region to be profiled.
.sp
.LP
The \fIbuffer\fR argument is the address of a user-supplied array of \fBWORD\fR
(defined in the header \fB<mon.h>\fR).  The \fIbuffer\fR argument is used by
\fBmonitor()\fR to store the histogram generated by \fBprofil()\fR and the call
counts.
.sp
.LP
The \fIbufsize\fR argument identifies the number of array elements in
\fIbuffer\fR.
.sp
.LP
The \fInfunc\fR argument is the number of call count cells that have been
reserved in \fIbuffer\fR. Additional call count cells will be allocated
automatically as they are needed.
.sp
.LP
The \fIbufsize\fR argument should be computed using the following formula:
.sp
.in +2
.nf
size_of_buffer =
        sizeof(struct hdr) +
        \fInfunc\fR * sizeof(struct cnt) +
        ((\fIhighpc\fR-\fIlowpc\fR)/\fIBARSIZE\fR) * sizeof(WORD) +
        sizeof(WORD) \(mi 1 ;
bufsize = (size_of_buffer / sizeof(WORD));
.fi
.in -2

.sp
.LP
where:
.RS +4
.TP
.ie t \(bu
.el o
\fIlowpc\fR, \fIhighpc\fR, \fInfunc\fR are the same as the arguments to
\fBmonitor()\fR;
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fIBARSIZE\fR is the number of program bytes that correspond to each histogram
bar, or cell, of the \fBprofil()\fR buffer;
.RE
.RS +4
.TP
.ie t \(bu
.el o
the \fBhdr\fR and \fBcnt\fR structures and the type \fBWORD\fR are defined in
the header \fB<mon.h>\fR\&.
.RE
.sp
.LP
The default call to \fBmonitor()\fR is as follows:
.sp
.in +2
.nf
monitor (&eprol, &etext, wbuf, wbufsz, 600);
.fi
.in -2

.sp
.LP
where:
.RS +4
.TP
.ie t \(bu
.el o
\fBeprol\fR is the beginning of the user's program when linked with \fBcc
\fR\fB-p\fR (see \fBend\fR(3C));
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBetext\fR is the end of the user's program (see \fBend\fR(3C));
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBwbuf\fR is an array of \fBWORD\fR with \fIwbufsz\fR elements;
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBwbufsz\fR is computed using the \fIbufsize\fR formula shown above with
\fIBARSIZE\fR of 8;
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fB600\fR is the number of call count cells that have been reserved in
\fIbuffer\fR.
.RE
.sp
.LP
These parameter settings establish the computation of an execution-time
distribution histogram that uses \fBprofil()\fR for the entire program,
initially reserves room for 600 call count cells in \fIbuffer\fR, and provides
for enough histogram cells to generate significant distribution-measurement
results. For more information on the effects of \fIbufsize\fR on
execution-distribution measurements, see \fBprofil\fR(2).
.SH EXAMPLES
.LP
\fBExample 1 \fRExample to stop execution monitoring and write the results to a
file.
.sp
.LP
To stop execution monitoring and write the results to a file, use the
following:

.sp
.in +2
.nf
monitor(\|(int (*)(\|)\|)0, (int (*)(\|)\|)0, (WORD *)0, 0, 0);
.fi
.in -2

.sp
.LP
Use \fBprof\fR to examine the results.

.SH USAGE
.sp
.LP
Additional calls to \fBmonitor()\fR after \fBmain()\fR has been called and
before \fBexit()\fR has been called will add to the function-call count
capacity, but such calls will also replace and restart the \fBprofil()\fR
histogram computation.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
MT-Level	Safe
.TE

.SH SEE ALSO
.sp
.LP
.BR profil (2),
.BR end (3C),
.BR attributes (7),
.BR prof (7)
